Node / meshtastic / Meshtastic-Android / files / docs / en / developer / navigation-and-deep-links.md

Displaying Rendered • View raw • Download

title: Navigation & Deep Links

parent: Developer Guide

nav_order: 4

last_updated: 2026-07-08

aliases:

• deeplinks

• navigation-3

• routes

The app uses Navigation 3 with typed, serializable routes and centralized deep link resolution.

All routes are defined in T383838core/navigation/src/commonMain/kotlin/org/meshtastic/core/navigation/Routes.kt.

T282828

Tff7b72interface T56d364Route Tb4b4b4: Te6edf3NavKey T8b949e// All routes implement NavKey

Tff7b72interface T56d364Graph Tb4b4b4: Te6edf3Route T8b949e// Graph roots for navigation hierarchies

Tf0883e@Serializable

Tff7b72sealed Tff7b72interface T56d364SettingsRoute Tb4b4b4: Te6edf3Route Tb4b4b4{

Tf0883e@Serializable Tff7b72data Tff7b72class T56d364SettingsTb4b4b4(Tff7b72val Te6edf3destNumTb4b4b4: Tffa657Int? Tff7b72= Tff7b72nullTb4b4b4) Tb4b4b4: Te6edf3SettingsRouteTb4b4b4, Te6edf3Graph

Tf0883e@Serializable Tff7b72data Tff7b72object T56d364DeviceConfiguration Tb4b4b4: Te6edf3SettingsRoute

Tf0883e@Serializable Tff7b72data Tff7b72object T56d364HelpDocs Tb4b4b4: Te6edf3SettingsRoute

Tf0883e@Serializable Tff7b72data Tff7b72class T56d364HelpDocPageTb4b4b4(Tff7b72val Te6edf3pageIdTb4b4b4: Tffa657StringTb4b4b4) Tb4b4b4: Te6edf3SettingsRoute

T8b949e// ...

Tb4b4b4}

• Routes are T383838@Serializable for state restoration

• Use T383838data object for routes without parameters

• Use T383838data class for parameterized routes

• Group related routes under a T383838sealed interface

• Graph entry points implement both the route interface and T383838Graph

T383838DeepLinkRouter in T383838core/navigation maps URI deep links to typed backstack lists.

Both forms resolve through the same T383838DeepLinkRouter, so any path below works with either scheme:

T282828

T383838adb shell am start -a android.intent.action.VIEW -d "meshtastic://meshtastic/{path}" is the fastest way to

trigger any route below from a shell or automation script without touching the UI.

For the T383838https form to open in-app, each top-level path segment must also be declared as an

T383838android:pathPrefix in the T383838android:autoVerify intent-filter in T383838androidApp/src/main/AndroidManifest.xml —

otherwise the link opens in the browser. Adding a new top-level route therefore takes three steps: add the

segment to T383838DeepLinkRouter.topLevelPathSegments (the router refuses to dispatch segments outside that set),

add its T383838when branch in T383838DeepLinkRouter.route(), and add the matching T383838pathPrefix to the manifest.

T383838DeepLinkManifestConsistencyTest (androidApp unit tests) checks the manifest against the set, so a missing

manifest entry fails CI.

Source of truth: the always-current list of top-level segments is T383838topLevelPathSegments in

— sub-paths live in the T383838route() T383838when block plus its helper maps (T383838settingsSubRoutes, T383838nodeDetailSubRoutes);

the class-level KDoc is illustrative, not exhaustive. It also exists as executable spec in

DeepLinkRouterTest.kt.

The table below is a snapshot for quick reference — check those two files if it looks out of date.

Deep links synthesize a full backstack, not just the target screen:

T282828

Te6edf3listOfTb4b4b4(

Te6edf3SettingsRouteTb4b4b4.Te6edf3SettingsTb4b4b4(Tff7b72nullTb4b4b4)Tb4b4b4,

Te6edf3SettingsRouteTb4b4b4.Te6edf3HelpDocsTb4b4b4,

Te6edf3SettingsRouteTb4b4b4.Te6edf3HelpDocPageTb4b4b4(Ta5d6ff"Ta5d6ffmessages-and-channelsTa5d6ff"Tb4b4b4)Tb4b4b4,

Tb4b4b4)

This ensures the user can navigate "up" correctly.

1. Define the typed route in T383838Routes.kt.

2. Add the mapping in T383838DeepLinkRouter.settingsSubRoutes (or equivalent for other graphs).

3. Add a test in T383838DeepLinkRouterTest.kt.

4. Register the navigation entry in the appropriate feature module.

5. Update the KDoc list on T383838DeepLinkRouter.route() and the table above — they're the two places tooling/agents look to discover what deep links exist.

Each feature module provides entries via an extension function:

T282828

Tff7b72fun Td2a8ffEntryProviderScopeTff7b72<Te6edf3NavKeyTff7b72>Tb4b4b4.Te6edf3docsEntriesTb4b4b4(Te6edf3backStackTb4b4b4: Te6edf3NavBackStackTff7b72<Te6edf3NavKeyTff7b72>Tb4b4b4) Tb4b4b4{

Te6edf3entryTff7b72<Te6edf3SettingsRouteTb4b4b4.Te6edf3HelpDocsTff7b72> Tb4b4b4{ Te6edf3DocsBrowserScreenTb4b4b4(Te6edf3backStackTb4b4b4) Tb4b4b4}

Te6edf3entryTff7b72<Te6edf3SettingsRouteTb4b4b4.Te6edf3HelpDocPageTff7b72> Tb4b4b4{ Te6edf3route Tff7b72-Tff7b72> Te6edf3DocsPageRouteScreenTb4b4b4(Te6edf3routeTb4b4b4.Te6edf3pageIdTb4b4b4, Te6edf3backStackTb4b4b4) Tb4b4b4}

Tb4b4b4}

These are called from the settings navigation composition.

Deep link routing is tested in:

T282828